home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 20 / Cream of the Crop 20 (Terry Blount) (1996).iso / program / vbprnt20.zip / VBPRINT.DOC < prev    next >
Text File  |  1996-05-31  |  30KB  |  737 lines
  1. VBPRINT Library v2.00 written by Robert Simpson (Black Castle Software, LLC)
  2.  
  3. This program has been released to the public domain.  No warranties are
  4. expressed or implied.  Use at your own risk.
  5.  
  6. ---Overview---
  7. This DLL allows your Visual Basic applications to have better control over the
  8. printer device.  It seems to be the one area MS has consistently forgotten in
  9. VB.
  10.  
  11. By far the easiest method for changing printer orientation, paper settings,
  12. trays, color and etc is to use the DEVMODE structure and make calls to the
  13. printer driver's ExtDeviceMode() function.  Unfortunately this particular
  14. function resides in the printer driver itself and VB cannot load that driver
  15. and call pointers to functions within it.  Therefore, I have written a set of
  16. printer control functions which do exactly that.  In addition, using the 
  17. VBResetDC() function, you can make changes to the printer orientation and 
  18. other settings during a print session (even if you're using VB's Printer
  19. object).
  20.  
  21. One of the problems of course is that not all DEVMODE structures are created
  22. equal.  Depending on the printer, the driver may append its own private data
  23. to the end of a DEVMODE structure, which further complicates the VB interface.
  24. The trick here is that all calls to VBPRINT use a special DEVMODE structure
  25. which I've modified for use with VB (hence called the VBDEVMODE).  This
  26. VBDEVMODE allows the VB Programmer access to all the important items in the
  27. DEVMODE structure and still allows the printer to have its own private area.
  28.  
  29.  
  30. ---Features---
  31. Ability to get/set the Windows default printer
  32. Ability to list all the installed printers
  33. Allows VB to call the ExtDeviceMode() function of a printer
  34. Also allows VB to call the DeviceCapabilities() function of a printer
  35. Has special VB version of ResetDC() to change printer settings on the fly
  36. Uses a special DEVMODE structure specifically tailored for VB
  37. Can convert a VBDEVMODE structure from and to a VB String so it can be easily
  38. saved to disk and restored later
  39. What this means is, you now have an easy method for changing print orientation
  40. and any other printer settings through the use of the VBDEVMODE structure.
  41.  
  42.  
  43. ---Flavors of this Library (and why there ARE flavors!!)---
  44. This library comes in 3 flavors so just about any VB programmer can use it
  45.  
  46. A VB3 version of the DLL (which is compatible with VB4/16-bit)
  47. A VB4/16-bit version (which is NOT compatible with VB3!!)
  48. A VB4/32-bit version (who's functions are identical to the VB4/16-bit version)
  49.  
  50. Why is the VB3 version compatible with VB4 and the VB4 version not compatible
  51. with VB3?  I decided that I wanted the VB4/32-bit and VB4/16-bit versions to
  52. be functionally identical, which meant that I had to allow for the fact that
  53. VB4/32-bit uses UNICODE strings (16-bits per character), and therefore I could
  54. not always write directly into memory because VB4 often does some unwanted
  55. translations when making function calls.
  56.  
  57. The particular function affected (and the ONLY one affected) is the
  58. VBDeviceCapabilities() function.  In the VB3 version, there is only ONE
  59. command, VBDeviceCapabilities().  Often this function returns an array of data
  60. to the user, which is no problem in VB3 or VB4/16-bit, you just pass the first
  61. dimension of the array (such as Names$(0) ) and the DLL can write all the
  62. elements of the array since they're stored linearly in memory.
  63. NOT SO in VB4/32-bit!!  If you pass Names$(0) to a DLL, VB4 translates it from
  64. UNICODE to ANSI and gives you a new pointer to JUST THAT DIMENSION, leaving me
  65. no place to put the rest of the items that are supposed to go in the array.
  66.  
  67. Therefore in order to make your VB code portable from 16-bits to 32-bits,
  68. the VB4 versions of the DLL have a VBDeviceCapArray() function, which is
  69. just an Alias to "VBDeviceCapabilities" but one that explicitly requires an
  70. array variable, which you would pass as Names$() (with NO numbers between the
  71. parens!).
  72.  
  73. So if you are porting a VB3 program to use the NEW VB4 VBPRNTxx library, you
  74. will need to replace commands such as:
  75.  
  76.   i = VBDeviceCapabilities(DefPrinter$,DC_PAPERNAMES,Names$(0),inDEV)
  77.  
  78. to the new format for arrays in the VB4 version:
  79.  
  80.   i = VBDeviceCapArray(DefPrinter$,DC_PAPERNAMES,Names$(),inDEV)
  81.  
  82. **THIS IS THE ONLY DIFFERENCE IN FUNCTION CALLS**
  83.  
  84.  
  85. ---Using this DLL with the Printer Object---
  86. Most printing in VB goes through the Printer object, which leaves much to be
  87. desired.  Normally in the Windows API you can pass a DEVMODE structure when
  88. you create a device context, which makes life much easier--you can include all
  89. your custom printer settings in the device open sequence and not have to
  90. bother with a bunch of subsequent Escape() functions.
  91. The VB Printer object doesn't allow this convenience.  Therefore if you must
  92. use the VB Printer object, you have two options:
  93. (Assuming you've already got a VBDEVMODE structure filled in with your desired
  94. settings)
  95. #1
  96. Use the Printer object's .hDC property and call VBResetDC() with the filled-
  97. in VBDEVMODE structure.  This is the easiest method...or...
  98.  
  99. #2
  100. Call VBExtDeviceMode() and get the printer's current settings (see the
  101. functions reference for instructions on doing this)
  102.  
  103. Make another call to VBExtDeviceMode() with your DEVMODE structure and tell
  104. the printer to use these settings as the new default settings.
  105.  
  106. Use the Printer object to your heart's content
  107.  
  108. When finished, one more call to VBExtDeviceMode() with the old default
  109. settings, restoring them back to the original.
  110.  
  111. Using the utilities in this DLL, you'll be able to change printers, use them
  112. in ways you were unable to do previously, and change back to the default
  113. printer all without an annoying dialog box or having to prompt the user.
  114.  
  115.  
  116. ---The DEVMODE structure---
  117. If you're familiar with the DEVMODE structure, this one should look strikingly
  118. similar.
  119.  
  120. Type DEVMODE_TYPE
  121.   dmDeviceName As String * 32 ' VB4/32 uses an array of Byte
  122.   dmSpecVersion As Integer
  123.   dmDriverVersion As Integer
  124.   dmSize As Integer
  125.   dmDriverExtra As Integer
  126.   dmFields As Long
  127.   dmOrientation As Integer
  128.   dmPaperSize As Integer
  129.   dmPaperLength As Integer
  130.   dmPaperWidth As Integer
  131.   dmScale As Integer
  132.   dmCopies As Integer
  133.   dmDefaultSource As Integer
  134.   dmPrintQuality As Integer
  135.   dmColor As Integer
  136.   dmDuplex As Integer
  137.   dmYResolution As Integer
  138.   dmTTOption As Integer
  139.   dmPrivate As String
  140. End Type
  141.  
  142. The 32-bit version adds several items to the above structure, and uses arrays
  143. of Byte instead of fixed-length strings because of the fact that strings are
  144. stored internally in UNICODE format (which means they're twice as large)
  145.  
  146.  
  147. The following is an exerpt from the Win3.1 SDK describing the elements of the
  148. DEVMODE structure:
  149.  
  150. dmDeviceName
  151. Specifies the name of the device the driver supports--for example, "PCL/HP
  152. LaserJet" in the case of the Hewlett-Packard LaserJet. Each driver has a
  153. unique string.
  154.  
  155. dmSpecVersion
  156. Specifies the version number of the DEVMODE structure. For Windows version
  157. 3.1, this value should be 0x30A.
  158.  
  159. dmDriverVersion
  160. Specifies the printer driver version number assigned by the printer driver
  161. developer.
  162.  
  163. dmSize
  164. Specifies the size, in bytes, of the DEVMODE structure. (This value does not
  165. include the optional dmDriverData member for device-specific data, which can
  166. follow the structure.) If an application manipulates only the driver-
  167. independent portion of the data, it can use this member to find out the length
  168. of the structure without having to account for different versions.
  169.  
  170. dmDriverExtra
  171. Specifies the size, in bytes, of the optional dmDriverData member for device-
  172. specific data, which can follow the structure. If an application does not use
  173. device-specific information, it should set this member to zero.
  174.  
  175. dmFields
  176. Specifies a set of flags that indicate which of the remaining members in the
  177. DEVMODE structure have been initialized. It can be any combination (or it can
  178. be none) of the following values:
  179.  
  180. Constant        Value
  181.  
  182. DM_ORIENTATION        0x0000001L 
  183. DM_PAPERSIZE        0x0000002L 
  184. DM_PAPERLENGTH        0x0000004L 
  185. DM_PAPERWIDTH        0x0000008L 
  186. DM_SCALE